home *** CD-ROM | disk | FTP | other *** search
/ TOS Silver 2000 / TOS Silver 2000.iso / programm / MM2_DEV / S / GEM / WINDOWLI.D < prev    next >
Encoding:
Modula Definition  |  1990-12-11  |  19.4 KB  |  452 lines
  1. DEFINITION MODULE WindowLists;
  2.  
  3. (*  System              : Megamax Modula-2
  4.  *  Autor & Copyright   : Manuel Chakravarty
  5.  *  Vertrieb            : Application Systems Heidelberg
  6.  *  Version             : V1.4
  7.  *)
  8.  
  9. (*  Dieses Modul dient zur weitgehend automatischen Verwaltung von Fenster,
  10.  *  deren Inhalt aus zeilenorientiertem Text besteht. Zur Beschreibung des
  11.  *  Fensterinhalts wird eine Liste verwendet, deren einzelne Elemente die
  12.  *  Daten für je eine Zeile des Fensters enthalten.
  13.  *
  14.  *  Eine Beispielanwendung zeigt das Modul 'WDWLists' im DEMO-Ordner!
  15.  *
  16.  *  Einige Bemerkungen zu den Fähigkeiten und der Programmierung
  17.  *  ------------------------------------------------------------
  18.  *
  19.  *  -- Jede Zeile eines Fensterliste kann mit einer Reihe von Attributen ver-
  20.  *     sehen werden, um sie zu kennzeichnen oder herauszuheben. Eine spezielle
  21.  *     Funktion erfüllt das Attribut 'selectWL' (Siehe 'DetectWindowWL' und
  22.  *     'SelectAreaWL').
  23.  *  -- Da die Abbildung der Listenelemente auf die angezeigten Zeichenketten
  24.  *     durch eine vom Klientenmodul bestimmte Prozedur erfolgt, ist das Format
  25.  *     der Listenelemente und der Zeichenketten beliebig. Die einzige Ein-
  26.  *     schränkung ist, daß ein Listeneintrag auf genau eine Textzeile im Fen-
  27.  *     ster abbgebildet werden muß.
  28.  *  -- Die Listen werden mit der Prozedur 'SetListWL' gesetzt und können mit
  29.  *     'GetListWL' wieder zurückgefordert werden. Ein Wechsel zwischen zwei
  30.  *     verschiedenen Listen ist auch während das Fenster offen ist möglich,
  31.  *     doch sollte 'GetListWL' und 'SetListWL' möglichst direkt aufeinander
  32.  *     folgen.
  33.  *  -- Beispiel für die Anwendung dieses Moduls sind die Directory- und Modul-
  34.  *     Fenster der Module-Shell oder die (noch) auszudruckenden Files eines
  35.  *     Druckerspoolers oder Kurzdarstellung aller Datensätze einer Datei.
  36.  *
  37.  *  Implementationshinweis: Dieses Modul basiert in seinen wesentlichen
  38.  *    Funktionen vollständig auf 'WindowBase' und einigen VDI-Routinen.
  39.  *)
  40.  
  41.  
  42. FROM SYSTEM     IMPORT ADDRESS;
  43.  
  44. FROM Strings    IMPORT String;
  45.  
  46. FROM Lists      IMPORT List;
  47.  
  48. FROM GrafBase   IMPORT Point, Rectangle;
  49.  
  50. FROM GEMGlobals IMPORT MaxStr;
  51.  
  52. FROM WindowBase IMPORT CenterWdw, MaxWdw;
  53.  
  54.  
  55. TYPE    WindowList;
  56.  
  57.         (*  Mögliche Attribute eines 'WindowList'-Eintrags.
  58.          *)
  59.  
  60.         AttributeWL      = (selectedWL, disabledWL, markedWL);
  61.         AttributesWL     = SET OF AttributeWL;
  62.  
  63.         (*  Diese, vom Klientenmodul zu stellende Prozedur, wandelt die Daten
  64.          *  eines Listenelements in die im Fenster darzustellende Zeichen-
  65.          *  kette um.
  66.          *)
  67.         EntryToStrProcWL= PROCEDURE (    (*entry      : *) ADDRESS,
  68.                                          (*environment: *) ADDRESS,
  69.                                      VAR (*str        : *) MaxStr);
  70.  
  71.         (*  Eine Prozedur diesen Typs wird aufgerufen, sobald der Anwender
  72.          *  den Close-Button eines Fenster angeklickt hat.
  73.          *)
  74.         CloseProcWL     = PROCEDURE ((*wl         : *) WindowList,
  75.                                      (*environment: *) ADDRESS   );
  76.  
  77.         (*  Eine Prozedur diesen Typs wird aufgerufen, sobald der Benutzer
  78.          *  einen Fenstereintrag angewählt hat.
  79.          *  Zusicherung: Diese Prozedur wird niemals für einen Eintrag auf-
  80.          *               gerufen, der das Attribut 'disabledWL' besitzt.
  81.          *)
  82.         SelectEntryProcWL= PROCEDURE ((*wl         : *) WindowList,
  83.                                       (*entry      : *) ADDRESS,
  84.                                       (*environment: *) ADDRESS,
  85.                                       (*selMode    : *) LONGCARD);
  86.  
  87.  
  88. CONST   NoWindowList    = WindowList (NIL);
  89.  
  90.         CenterWindowWL  = CenterWdw;    (*  Hor./vert. zentriert          *)
  91.         MaxWindowWL     = MaxWdw;       (*  Maximale Fensterbreite/-höhe  *)
  92.  
  93.  
  94.  
  95.                         (*  Verwaltungsroutinen  *)
  96.                         (*  ===================  *)
  97.  
  98. PROCEDURE CreateWL (VAR wl      : WindowList;
  99.                         infoline: BOOLEAN;
  100.                         size    : Rectangle);
  101.  
  102.         (*  Dient zum Erzeugen einer neuen Fensterliste.
  103.          *
  104.          *  Dabei gibt 'size' die anfänglichen Ausmaße des Fensters in Zeichen-
  105.          *  koordinaten an. Als Sonderwerte dürfen auch 'CenterWindowWL' und
  106.          *  'MaxWindowWL' angegeben werden.
  107.          *  Ist 'infoLine = TRUE', so erhält das Fenster eine Informations-
  108.          *  zeile.
  109.          *
  110.          *  Ist danach 'StateWL (wl) = invalidWL', so konnte die Fensterliste
  111.          *  nicht korrekt erzeugt werden.
  112.          *)
  113.  
  114. PROCEDURE SysCreateWL (VAR wl      : WindowList;
  115.                            infoline: BOOLEAN;
  116.                            size    : Rectangle);
  117.  
  118.         (*  Dient zum Erzeugen einer Fensterliste, die bei Modulterminierung
  119.          *  nicht automatisch abgemeldet wird.
  120.          *
  121.          *  Parameter entsprechen 'SysCreateWL'.
  122.          *)
  123.  
  124. PROCEDURE DeleteWL (VAR wl: WindowList);
  125.  
  126.         (*  Dient zum Freigeben einer nicht mehr benötigten Fensterliste.
  127.          *)
  128.  
  129. PROCEDURE SetListWL (    wl         : WindowList;
  130.                          l          : List;
  131.                          entryToStr : EntryToStrProcWL;
  132.                          closeWList : CloseProcWL;
  133.                          selectEntry: SelectEntryProcWL;
  134.                          environment: ADDRESS;
  135.                          width      : CARDINAL;
  136.                      REF title      : ARRAY OF CHAR);
  137.  
  138.         (*  Diese Routine dient zum Spezifizieren des Inhalts und des
  139.          *  Verhaltens einer Fensterliste und zum Setzen des Fonts
  140.          *  (Zeichensatz).
  141.          *
  142.          *  Dabei ist 'l' eine Liste, deren Elemente den Inhalt je einer
  143.          *  Zeile des Fensterinhaltes bestimmen, 'entryToStr' eine Pro-
  144.          *  zedur, die ein Listenelement in die darzustellende Zeichen-
  145.          *  kette umwandelt. 'closeWList' wird beim Anklicken des Close-
  146.          *  Buttons und 'selectEntry' beim Anklicken einer Fensterzeile
  147.          *  mittels 'DetectWindowWL' aufgerufen. 'environment' wird beim
  148.          *  Aufruf jeder der drei vorangegangenen Prozeduren mit übergeben
  149.          *  und steht dem Klientenmodul zur freien Verfügung (Ersatz einer
  150.          *  dynamischen Aufrufumgebung). Außerdem legt 'width' die maximale
  151.          *  Breite eines Fenstereintrages und 'title' den Fenstertitel fest.
  152.          *
  153.          *  ACHTUNG: Die Liste 'l' darf nach diesem Aufruf nicht mehr vom
  154.          *           Klientenmodul verwendet werden (weder schreibend noch
  155.          *           lesend). Siehe auch 'GetListWL'.
  156.          *           Die in 'l' verwalteten Adressen müssen paarweise ver-
  157.          *           schieden und ungleich 'NIL' sein.
  158.          *
  159.          *  Um den Font zu setzen, ist für "entryToStr" 'EntryToStrProcWL(NIL)'
  160.          *  zu übergeben.
  161.          *  'width' bestimmt dann die Zeichenhöhe in Punkt (s. SetPtsTHeight)
  162.          *  und 'title' bestimmt den Namen des Fonts. Die restlichen Parameter
  163.          *  sind unbenutzt und dürfen beliebige Werte enthalten.
  164.          *  Wird 'NoWindowList' in 'wl' übergeben, wird der Default-Font
  165.          *  bestimmt, der beim Anlegen (CreateWL) aller neuen Fenster benutzt
  166.          *  wird. Ansonsten wird der aktuelle Font des angegebenen Fensters
  167.          *  ersetzt.
  168.          *)
  169.  
  170. PROCEDURE GetListWL (wl: WindowList; VAR l: List);
  171.  
  172.         (*  Hiermit erhält das Klientenmodul wieder Zugriff auf eine mit
  173.          *  'SetListWL' übergeben Liste. Zugleich werden alle anderen
  174.          *  mit diesem 'SetListWL' gemachten Angaben aufgehoben.
  175.          *
  176.          *  ACHTUNG: Falls die Fensterliste 'wl' zum Zeitpunkt dieses Auf-
  177.          *           rufs sichtbar ist, so muß sichergestellt werden, daß
  178.          *           keine Aktionen ausgelößt werden, die dieses Fenster
  179.          *           betreffen, bis es entweder versteckt wird oder mit
  180.          *           'SetListWL' erneut gültige Parameter erhält.
  181.          *)
  182.  
  183. PROCEDURE ShowWindowWL (wl: WindowList);
  184.  
  185.         (*  Die Fensterliste wird auf dem Bildschirm dargestellt oder falls
  186.          *  sie schon sichtbar war, neu gezeichnet.
  187.          *)
  188.  
  189. PROCEDURE HideWindowWL (wl: WindowList);
  190.  
  191.         (*  Die Fensterliste wird vom Bildschirm entfernt.
  192.          *)
  193.  
  194. PROCEDURE EnhancedOutputWL (wl: WindowList; enhanced: BOOLEAN);
  195.  
  196.         (*  Aktiviert die schnelle Übergabe von Daten an das Modul, ohne
  197.          *  daß dabei Fensterbereiche neu gezeichnet werden.
  198.          *
  199.          *  Wird hiermit der Enhanced-Mode angeschaltet, so wird der
  200.          *  Fensterinhalt nicht mehr neu gezeichnet, bis der Enhanced-Modus
  201.          *  wieder abgeschaltet wird. Beim Abschalten wird der komplette
  202.          *  Fensterinhalt auf einen Schlag neu gezeichnet.
  203.          *)
  204.  
  205. TYPE    ErrorStateWL    = (okWL, listNotSetWL, wdwNotOpenWL, unkownEntryWL,
  206.                            listFaultWL, outOfMemoryWL, cantShowWL, invalidWL);
  207.  
  208. PROCEDURE StateWL (wl: WindowList): ErrorStateWL;
  209.  
  210.         (*  Der aktuelle Fehlerzustand der Fensterliste wird geliefert.
  211.          *
  212.          *  Dabei bezieht sich der aufgetrettenen Fehler immer auf die vor-
  213.          *  angegangene Operation. Ist ein Fehler erkannt worden, so sollte
  214.          *  anschließend 'ResetStateWL' aufgerufen werden, da sonst bei der
  215.          *  nächsten Operation ein Laufzeitfehler ausgelößt wird.
  216.          *
  217.          *  'okWL'         -- Kein Fehler.
  218.          *  'listNotSetWL' -- Es ist kein gültiger 'SetListWL'-Aufruf durch-
  219.          *                    worden, obwohl dies vor der letzten Operation
  220.          *                    nötig gewesen wäre.
  221.          *  'wdwNotOpenWL' -- Das Fenster ist nicht auf dem Bildschirm dar-
  222.          *                    gestellt, obwohl dies für die letzte Operation
  223.          *                    notwendig gewesen wäre.
  224.          *  'unkownEntryWL'-- Das Klientenmodul hat der letzten Operation
  225.          *                    einen Listeneintrag genannt, der nicht in der
  226.          *                    benutzen Liste enthalten ist.
  227.          *  'listFaultWL'  -- Interner Fehler.
  228.          *  'outOfMemoryWL'-- Der letzten Operation wurde der benötigte
  229.          *                    Speicher nicht vom Betriebssystem zur Verfügung
  230.          *                    gestellt.
  231.          *  'cantShowWL'   -- Die Fensterliste kann nicht auf dem Bildschirm
  232.          *                    dargestellt werden.
  233.          *  'invalidWL'    -- 'wl' ist keine gültige Referenz auf eine Fenster-
  234.          *                    liste.
  235.          *)
  236.  
  237. PROCEDURE ResetStateWL (wl: WindowList);
  238.  
  239.         (*  Setzt den aktuellen Fehlerzustand auf 'okWL'.
  240.          *
  241.          *  Sollte nach jedem erkannten Fehler aufgerufen werden (siehe auch
  242.          *  'StateWL'). Die einzige Ausnahme ist 'inavlidWL'.
  243.          *)
  244.  
  245.  
  246.                         (*  Listenoperationen  *)
  247.                         (*  =================  *)
  248.  
  249. PROCEDURE AddEntryWL (wl: WindowList; entry, predEntry: ADDRESS);
  250.  
  251.         (*  Fügt einen Eintrag in eine Fensterliste ein.
  252.          *
  253.          *  Dabei wird 'entry' nach 'predEntry' eingefügt. Ist 'predEntry
  254.          *  = NIL', so wird am Listenanfang eingefügt.
  255.          *)
  256.  
  257. PROCEDURE AppendEntryWL (wl: WindowList; entry: ADDRESS);
  258.  
  259.         (*  Hängt einen Eintrag an eine Fensterliste an.
  260.          *)
  261.  
  262. PROCEDURE RemoveEntryWL (wl: WindowList; entry: ADDRESS);
  263.  
  264.         (*  Entfernt einen Eintrag aus einer Fensterliste.
  265.          *)
  266.  
  267. PROCEDURE ReplaceEntryWL (wl        : WindowList;
  268.                           oldEntry,
  269.                           newEntry  : ADDRESS;
  270.                           keepAttrs : BOOLEAN);
  271.  
  272.         (*  Ersetzt einen Eintrag einer Fensterliste durch einen neuen.
  273.          *
  274.          *  Dabei gibt 'keepAttrs = TRUE' an, daß der neue Eintrag die
  275.          *  Attribute des alten übernehmen soll.
  276.          *)
  277.  
  278. TYPE    QueryDirectionWL   = (forwardWL, backwardWL);
  279.         QueryProcWL        = PROCEDURE (    (* entry: *) ADDRESS,
  280.                                             (* env  : *) ADDRESS,
  281.                                         VAR (* attrs: *) AttributesWL): BOOLEAN;
  282.  
  283. PROCEDURE QueryListWL (    wl   : WindowList;
  284.                            dir  : QueryDirectionWL;
  285.                            proc : QueryProcWL;
  286.                            env  : ADDRESS;
  287.                        VAR cut  : BOOLEAN;
  288.                        VAR entry: ADDRESS);
  289.  
  290.         (*  Ruft eine Prozedur für jedes Element einer Liste auf. Dabei ist
  291.          *  sowohl die Laufrichtung frei wählbar, als es der auf die Listen-
  292.          *  elemente angewendeten Prozedur auch freisteht den Vorgang abzu-
  293.          *  brechen.
  294.          *
  295.          *  Für jedes Listenelement der Liste von 'wl' wird 'proc' aufgerufen
  296.          *  und bekommt dabei die Elementreferenz 'entry' und die für dieses
  297.          *  Element gesetzten Attribute 'attrs' übergeben. Durch Rückgabe
  298.          *  des Wertes 'FALSE' kann 'proc' den Vorgang unterbrechen, dessen
  299.          *  Laufrichtung durch 'dir' festgelegt wird. Dabei beginnt 'forwardWL'
  300.          *  am Listenanfang und 'backwardWL' am Listenende.
  301.          *  Liefert 'cut' den Wert 'TRUE', so wurde der Vorgang durch 'proc'
  302.          *  abgebrochen, sonst sind alle Elemente durchlaufen worden. Auf
  303.          *  jeden Fall liefert 'entry' den Eintrag, der als letzter an 'proc'
  304.          *  übergeben wurde.
  305.          *  Wird der Parameter 'attrs' geändert, so wird der neue Wert über-
  306.          *  nommen und das entsprechende Element neu gezeichnet.
  307.          *
  308.          *  ACHTUNG: 'proc' darf auf keine Fall destruktive Listenoperationen
  309.          *           auf die Liste von 'wl' anwenden.
  310.          *)
  311.  
  312. PROCEDURE EntryAttributesWL (wl: WindowList; entry: ADDRESS): AttributesWL;
  313.  
  314.         (*  Liefert die Attribute eines Listeneintrags (einer Fensterzeile).
  315.          *)
  316.  
  317. PROCEDURE SetEntryAttributesWL (wl   : WindowList;
  318.                                 entry: ADDRESS;
  319.                                 attrs: AttributesWL);
  320.  
  321.         (*  Setzt die Attribute eines Listeneintrags (einer Fensterzeile).
  322.          *)
  323.  
  324. PROCEDURE GetEntryBoxWL (    wl     : WindowList;
  325.                              entry  : ADDRESS;
  326.                          VAR box    : Rectangle;
  327.                          VAR visible: BOOLEAN);
  328.  
  329.         (*  Liefert das kleinste Rechteck, das einen Eintrag völlig um-
  330.          *  schließt.
  331.          *
  332.          *  Dabei werden in 'box' die absoluten Pixelkoordinaten über-
  333.          *  geben.
  334.          *  Ist 'visible = FALSE', so ist kein Auschnitt von 'entry' in-
  335.          *  nerhalb des sichtbaren Fensterbereichs.
  336.          *)
  337.  
  338.  
  339.                         (*  Fensteroperationen  *)
  340.                         (*  ==================  *)
  341.  
  342. PROCEDURE SetInfoLineWL (wl: WindowList; REF infoStr: ARRAY OF CHAR);
  343.  
  344.         (*  Weist der Informationszeile des Fensters einen neuen Text zu.
  345.          *)
  346.  
  347. PROCEDURE ViewLineWL (wl: WindowList; line: CARDINAL);
  348.  
  349.         (*  Scrollt das Fenster derart, daß die angegebene Zeile
  350.          *  möglichst mittig sichtbar ist.
  351.          *
  352.          *  Zählung der Zeilen beginnt bei 1.
  353.          *)
  354.  
  355. PROCEDURE SetWindowSizeWL (wl: WindowList; size: Rectangle);
  356.  
  357.         (*  Setzt die Ausmaße des Fensterarbeitsbereichs in Zeichen-
  358.          *  koordinaten.
  359.          *
  360.          *  Die Sonderwerte 'CenterWindowWL' und 'MaxWindowWL' sind
  361.          *  erlaubt.
  362.          *)
  363.  
  364. PROCEDURE PutWindowOnTopWL (wl: WindowList);
  365.  
  366.         (*  Macht das Fenster zum oben aufliegenden Fenster.
  367.          *)
  368.  
  369. PROCEDURE WindowSizeWL (wl: WindowList): Rectangle;
  370.  
  371.         (*  Liefert die aktuellen Ausmaße des Fensterarbeitsbereichs
  372.          *  in Zeichenkoordinaten.
  373.          *)
  374.  
  375. PROCEDURE IsTopWindowWL (wl: WindowList): BOOLEAN;
  376.  
  377.         (*  Ermittelt ob das Fenster einer Fensterliste, das oberste
  378.          *  aller sichtbaren Fenster ist.
  379.          *)
  380.  
  381. TYPE    DetectModeWL    = (scanWL, selectWL);
  382.  
  383. PROCEDURE DetectWindowWL (REF targets: ARRAY OF WindowList; noTrg: CARDINAL;
  384.                               loc    : Point;
  385.                               mode   : DetectModeWL;
  386.                               selMode: LONGCARD;
  387.                           VAR wl     : WindowList;
  388.                           VAR entry,
  389.                               env    : ADDRESS;
  390.                           VAR empty  : BOOLEAN);
  391.  
  392.         (*  Dient zum Feststellen des Fensterinhaltes an einer bestimmten
  393.          *  Bildschirmposition (z.B. Mauszeiger).
  394.          *
  395.          *  Dabei werden in 'targets' alle Fensterlisten übergeben, von
  396.          *  denen festgestellt werden soll, ob ihre Fenster die Bildschirm-
  397.          *  position 'loc' (absolute Pixelkoordinaten) belegen. In 'targets'
  398.          *  dürfen Enträge auch den Wert NoWindowList' annehmen. Die Anzahl
  399.          *  der zu berücksichtigenden Elemente von 'targets' wird in 'noTrg'
  400.          *  angegeben; ist dieser Wert '0', so werden alle Elemente ausge-
  401.          *  wertet.
  402.          *  Außerdem gibt 'mode' an, ob für einen eventuell an dieser Position
  403.          *  befindlichen Fenstereintrag die Prozedur 'selectEntry', der zuge-
  404.          *  hörigen Fensterliste aufgerufen werden soll. Bei einem solchen
  405.          *  Aufruf wird 'selMode' als ein frei vom Klientenmodul zu benutzender
  406.          *  Parameter übergeben. Der Aufruf findet bei Übergabe von 'selectWL'
  407.          *  statt.
  408.          *  Folgende vier Fälle können unterschieden werden:
  409.          *
  410.          *    i)   An der angegebenen Position befindet sich überhaupt kein
  411.          *         Fenster, gleichgültig ob es eine Fensterliste oder in
  412.          *         'targets' angegeben ist.
  413.          *         Daraufhin liefert 'empty' den Wert 'TRUE', alle anderen
  414.          *         VAR-Parameter sind undefiniert.
  415.          *
  416.          *    ii)  An der angegebenen Position liegt zwar ein Fenster, doch
  417.          *         ist es nicht in 'targets' eingetragen.
  418.          *         Es liefert 'empty' den Wert 'FALSE' und 'wl' enthält den
  419.          *         Wert 'NoWindowList'.
  420.          *
  421.          *    iii) An der Position liegt ein in 'targets' eingetragenes Fen-
  422.          *         ster, doch befindet sich dort kein Fenstereintrag.
  423.          *         So ist 'empty = FALSE', 'wl' enthält eine Referenz auf das
  424.          *         gefundene Fenster und 'env' den bei dem letzten 'SetListWL'
  425.          *         Aufruf mit dieser Referenz übergenen Parameter 'environment'.
  426.          *         Außerdem ist 'entry = NIL'.
  427.          *
  428.          *    iv)  Entspricht in Voraussetzung und Nachbedinung iii), doch
  429.          *         befindet sich an der angegebenen Position innerhalb des
  430.          *         Fensters ein Eintrag.
  431.          *         Dessen Referenz in der Fensterliste wird in 'entry' ge-
  432.          *         liefert.
  433.          *)
  434.  
  435. PROCEDURE SelectAreaWL (wl             : WindowList;
  436.                         area           : Rectangle;
  437.                         firstSelMode,
  438.                         reminderSelMode: LONGCARD);
  439.  
  440.         (*  Dient zum Selektieren einer einer zusammenhängenden Reihe von
  441.          *  Einträgen.
  442.          *
  443.          *  Dabei wird für alle Einträge der Fensterliste 'wl', die in dem
  444.          *  Bereich 'area' (absolute Pixelkoordinaten) liegen, die Prozedur
  445.          *  'selectEntry' der Fensterliste aufgerufen. Es wird beim ersten
  446.          *  Aufruf 'firstSelMode' und danach 'reminderSelMode' als vom
  447.          *  Klieentenmodul frei zu definierender Parameter übergeben.
  448.          *)
  449.  
  450.  
  451. END WindowLists.
  452.